package com.quantum.platform.event
{

	import flash.events.Event;

	[SDK]
	/**
	 * Represents the addition or removal of an object from the system. Certain classes of
	 * objects such as display objects are notified through other means, so this event is
	 * mostly useful for object types that are not already taken care of by flex framework
	 * events.
	 *
	 * <p>SDK Version 1.0.0</p>
	 */
	public class ObjectEvent extends Event
	{
		/**
		 * Event type id for notifying the addition of an object to the system.
		 */
		public static const OBJECT_ADDED:String="objectAdded";

		/**
		 * Event type id for notifying the removal of an object from the system.
		 */
		public static const OBJECT_REMOVED:String="objectRemoved";

		/**
		 * Initializes an instance of this class.
		 *
		 * @param type
		 *    The id for the event.
		 * @param object
		 *    Value for the object property.
		 */
		public function ObjectEvent(type:String, object:Object=null, bubbles:Boolean=true)
		{
			super(type, bubbles);
			_object=object;
		}

		/**
		 * Creates a clone of this event. All custom events should override this method.
		 *
		 * @return
		 *    A clone of this event.
		 */
		public override function clone():Event
		{
			var ev:ObjectEvent=new ObjectEvent(super.type, _object, super.bubbles);
			ev.isWeakReferencingMandatory=_isWeakReferencingMandatory;
			return ev;
		}

		//---------------------------------------------------------------------------
		// Class Methods

		/**
		 * A convenience factory method to create an instance of this class that represents
		 * the addition of a new object to the system.
		 */
		public static function newRemoval(object:Object):ObjectEvent
		{
			return new ObjectEvent(OBJECT_REMOVED, object);
		}

		/**
		 * A convenience factory method to create an instance of this class that represents
		 * the removal of an existing object from the system.
		 */
		public static function newAddition(object:Object, useWeakReference:Boolean=false):ObjectEvent
		{
			var event:ObjectEvent=new ObjectEvent(OBJECT_ADDED, object);
			event.isWeakReferencingMandatory=useWeakReference;
			return event;
		}

		//-------------------------------------------------------
		// Property: object

		private var _object:Object;

		/**
		 * The object whose addition or removal from the system is being notified.
		 */
		public function get object():Object
		{
			return _object;
		}

		//-------------------------------------------------------
		// Property: isWeakReferencingMandatory

		private var _isWeakReferencingMandatory:Boolean=false;

		/**
		 * This property is meaningful only for an <code>objectAdded</code> event and indicates
		 * to the recipients of this event (e.g., platform services) whether they are required
		 * to reference the object through weak-references only.
		 *
		 * <p>If this flag is set to true, the object should become a candidate for garbage
		 * collection once the client removes all its references to the object; in other words,
		 * the client should never have to raise the <code>objectRemoved</code> event for the
		 * said object. The services that require strong-referencing of the object will not be
		 * provided for this object.
		 *
		 * <p>The default value of this property is false.
		 */
		public function get isWeakReferencingMandatory():Boolean
		{
			return _isWeakReferencingMandatory;
		}

		public final function set isWeakReferencingMandatory(value:Boolean):void
		{
			_isWeakReferencingMandatory=value;
		}
	} // class

}